home *** CD-ROM | disk | FTP | other *** search
/ Software USA 4 #4 / Software USA Volume 4.04.iso / mac / Home and Office / Grapple / Grapple ReadMe < prev    next >
Encoding:
Text File  |  1998-02-12  |  21.2 KB  |  438 lines  |  [ttro/ttxt]

  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                                                     © 1998, Robin Harmon, PlaNet-3 Software.
  7.                                         Internet: http://exo.com/~clover/p3
  8.                                                                     Email: r.harmon@kagi.com
  9.  
  10. A Quick Outline.
  11.  
  12. Grapple is a Shareware string finder for the Macintosh. Originally based on the unix utility grep, Grapple has evolved to be much more of a Macintosh application with a friendly and intuitive interface. Grapple is also faster than any other other string finder that we could find! 
  13.  
  14. Grapple is very simple to use and fun. Set up a string that you wish to find, tell it where to start and hit the search button. Grapple then searches recursively through the folder hierarchy for files of the type (or types) chosen containing the desired string. Any matched strings are extracted and listed in a window for you to browse through. When the search is finished (or you stop it) you can select any file from those listed and either view it from within Grapple, have the Finder display its location or open it with the editor of your choice - all at the press of a button!
  15.  
  16. Give Grapple a try!  Whether it be a lost mail message, a vaguely remembered idea that is lost in a sea of business reports or the definition of a C function in one of a few hundred source-code files Grapple will find it!  Experiment and see for yourself!
  17.  
  18. Grappple runs on any Macintosh equipped with System 7 or later with 500K of free memory.
  19.  
  20. Grapple is easy to use, and easy to register too! You can pay by Credit card, American Express, First Virtual, Net Cash, cash, USD check or invoice! You can even register on-line at 
  21.  
  22.                                                        http://kagi.direct.net/cgi-bin/register1.cgi?HA
  23.  
  24. Please see the section on registration below for more details.
  25.  
  26. New in Version 1.3!
  27.  
  28.     •    now faster than any other string finder tested!  
  29. Improvements since version 1.2 mean that Grapple beats all of the following in a search through a randomly chosen folder containing just over 2500 TEXT files: UltraFind, File Buddy, FileSafari, Find in Files, QuickSearch, Retrieve-It and SpeedSearch - see the website for details!.
  30.  
  31.     •    now correctly displays files created on PCs and Unix machines.
  32.  
  33.     •    search results can now be exported as text for use in other applications.
  34.  
  35.  
  36. Feature Summary.
  37.  
  38.     •    Grapple lets you search quickly from a specified starting folder
  39.                     Choose your search options:
  40.           -  recursive through sub-folders or not
  41.                     -    case sensitive or not
  42.                     -    aliases can be followed or ignored
  43.                     -    set a maximum size or search files of any size
  44.                     -    set a range of last modification dates or ignore them
  45.  
  46.     •    Set up your favorite file types to search
  47.                     -    group file types together to search general classes of files
  48.  
  49.     •    Build a menu of your favorite folders to search
  50.           -  easily accessed from the main dialog
  51.                     -    you can just drag a folder or disk over the Grapple icon to start a search from there
  52.  
  53.     •    See at a glance how the search is proceeding
  54.                     - halt a search midway at the press of a button
  55.  
  56.     •    Background searches are fast and painless
  57.  
  58.     •    Results of a search are listed clearly in the Results Window. After a search you can view either
  59.           -  snippets of text centered on your search string, or
  60.           -  one line of information, including statistics, for each file containing a match 
  61.  
  62.     •    Button options allow you to:
  63.                     -    open files containing a match using your favourite editor  
  64.                     -    open files using the parent application  
  65.                     -    view text of files from within Grapple
  66.                     -    find and open the parent folder and select the file's icon
  67.  
  68.     •    Save the search results for later use. Results can be exported for use in other applications.
  69.  
  70.   •  Multiple search windows are indexed on the Menu Bar
  71.  
  72.     •    Summary statistics of all your searches to date are kept and can be seen in "About Grapple…"
  73.  
  74. The details.
  75.  
  76. 1) Search Strategy.
  77.  
  78. The main Grapple window allows you to define the search parameters. It looks like this:
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92. You must specify a search string and the starting point for the search. In this example the search will be for the word "memory" and will be from the folder "News Groups" on the volume "Net Stuff". 
  93.  
  94. The search will not be case sensitive and no part of the filename was specified. A partial filename could have been typed had it been known it. 
  95.  
  96. The File Type popup menu lists the type of file that will be searched and can be any type or combination of types you choose - see below. 
  97.  
  98. The downward arrow beside Start Folder is a popup menu of your favourite folders to start from. You can add or delete starting folders from this. 
  99.  
  100. The "More Options…" button reveals further ways in which you can control the search. The Grapple dialog expands to look like this:
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117. You can choose to stay in the start folder or descend the folder tree recursively and whether to follow aliases that may be found in the search or ignore them. 
  118.  
  119. Another popup menu is displayed that enables you search through just the Data fork of a file, just the Resource fork, or both if you wish. Normally you will only search the data fork as that is where editors and word processors store their text.
  120.  
  121. Two new options added in version 1.2 allow you to further limit the files Grapple will search by specifying a maximum size in the Size popup and a range of dates for the time they were last modified! To set a range of acceptable modification dates check the box beside the pair of dates and click in the month, day or year fields of either date to show the date adjuster arrows. Click in the up or down arrows to change that date field. By default the dates bracket a range in which to search but you can set up a pair of dates such that a range of dates is excluded if you like.
  122.  
  123. 2) The Results Window.
  124.  
  125. As the search procedes you can view the resulting matches either in context, surrounded by a snippet of text from the file, or as a summary line for each file listing the number of matches found in the file and other features of the file - much like the Finder's alternate views of the contents of a folder.
  126.  
  127. 2.1) Viewing Extracts
  128. If you choose "View Extracts" in the "Views" menu then the search results will be displayed like this:
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152. The search string is displayed in bold red text by default! The format of the display and hiliting can be adjusted with the "Extracts View…" option in the Preferences submenu of the Edit menu. 
  153.  
  154. The matched strings are extracted from their parent file along with a line of text to show the context of the match.  Each line begins with the line number of the match in the parent file and each block of matches has a header giving the path to the file. If your search included resource forks of files and a string was found in one then the file name would be followed by the characters "-r-". 
  155.  
  156. 2.2) Viewing Lists
  157. If you choose "View Extracts" in the "Views" menu then the search results will be displayed like this:
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181. Each line can contain any number of items of information chosen from the list: size, number of matches, type code, creator code, creation date, modification date, kind, label and data/resource fork tag in addition to the name. You can show or hide a column of information using the Show submenu of the Views menu.
  182.  
  183. Clicking on any of the column headings causes the list to be sorted on that column and re-displayed so you can easily find the file containing the largest number of matches for example! The list of extracts is also re-ordered after the search.
  184.  
  185. One particularly useful feature is the ability to select a file in one of the two views and switch to the other view where the file is centered in the window and already hilited. You can, for example, find the file containing the largest number of matches in the List View, select it and switch to the Extracts View to check on their context.
  186.  
  187. 2.3) The Button Bar
  188. The buttons at the bottom of the results window present you with 4 choices. You can either
  189.         1) Open the file with the default editor (set to Alpha in the example above, use the "Open Prefs…" dialog to select).
  190.         2) Open the file with its parent application - here "SimpleText" itself.
  191.         3) Make the Finder locate the file and display it hilited in its parent folder.
  192.         4) View the contents of the file selecting the first occurrence of the string (here on line 173 of the file).
  193.  
  194. This window (perhaps the results of a few minutes of searching) can be saved and opened by Grapple at a later date. The contents can then be accessed in exactly the same way.
  195.  
  196. The length of text that can be displayed in the Results Window is limited to about 30K. This is not a serious limitation as you will generally have found several hundred matches if you collect this much text! If you do find this a problem then try restricting the search by specifying fewer file types, fewer folders, a partial filename, a maximum file size or a range of modification dates. The search will procede faster the more you restrict the number of files to check!
  197.  
  198. 3) The Text View Window.
  199.  
  200. When you click on the "View Text" button of the Found-Window, Grapple opens the file and displays its contents centered on the first occurrence of the matched string. The string is selected like this:
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220. You can search forwards to the next occurrence of the search string with the "Find Next" menu option or backwards to the last with "Find Last". If you would like to search this file for a different string altogether just choose "Find…" then type your new string. Your new search can continue from the present position or restart from the beginning of the file. It can be case sensitive or not as you choose.
  221.  
  222. The amount of text that can be displayed in this window is limited to about 30K. If the file is larger than this then a block of this size will be read in, allowing you to view the region around the found string.
  223.  
  224. 4) File Types.
  225.  
  226. Macintosh applications create files of a particular type and signature so that they can recognise them as their daughters at a later time. You can introduce Grapple to files of different types using the "Add a Type…" menu option. This asks you to choose a file of the type you want and then prompts you for a name for such files. Your type is then added to those available on the File Type popup menu in the main Grapple window. The next time you search a bunch of files your search  can then be restricted to files of only this type and signature.
  227.  
  228. You may want to search through files of more than one type and Grapple allows you to do this through the "Group Types…" menu option. This presents you with a list of your current types and allows you to pick a subset that you wish to group together for future searches. Once again you are prompted for a name for this combined group and this will be added to the File Type popup menu.
  229.  
  230. Of course, at some stage you may wish to delete a file type or group and this can be achieved through the "Delete a Type…" menu option.
  231.  
  232. There are two special types that are already included in Grapple's popup menu. The "Any Type" item will search every kind of file encountered, so long as they meet the other search criteria. The "Plain Text" item will search any text file or read-only text file without regard to its parent application (the signature is ignored). Some popular applications, eg word processors, mail readers etc, produce files containing text, but have file types of their own. Grouping "Plain Text" with these file types is a powerful means of searching all of your text-containing files at once.
  233.  
  234. 5) Preferences.
  235. You can set many features of Grapple to start up in the way you prefer using the Preferences submenu on the Edit menu.
  236.  
  237. 5.1) General...
  238. The General Preferences dialog looks like this:
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259. You can choose whether to view the splash screen or not (if you are a registered user). You can have the progress dialog automatically disappear at the end of a search if you like. You can switch off the prompt that offers to save your search results if you hardly ever save them anyway and you can choose between the alternative views of search results - whether to have your search results presented as a list of summary lines, one per file, or as a set of extracts.  And you can force the Results window to be automatically resized at the end of a search to display the maximum number of files.
  260.  
  261. 5.2) Fonts...
  262. The fonts preference dialog is simple and allows you to set the font and text size of for the results of searches.
  263.  
  264. 5.3) Extracts View...
  265. The appearance of the text in  the Results window is controlled by the Extracts View dialog. It looks like this:
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283. The maximum number of characters to extract from a file, centered on the matching text, can be changed from the default of 80 up to a maximum of 255. If Grapple finds nearby carriage return characters then the extracted text will not extend past these. The position of the matching string in the file can be labeled with either a line number, a byte count or omitted altogether.
  284.  
  285. The Hiliting controls determine how to display the matching set of characters in the extracted text. You can set the color and style of the matching text.
  286.  
  287. 5.4) List View...
  288. The List View preference dialog looks like this:
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303. Just select the file characteristics you want to see in the List View and click OK!
  304.  
  305. 5.5) Opening...
  306. The leftmost button at the bottom of a Results window opens the selected file with the default editor. You can set this editor using the "Opening…" dialog:
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328. Grapple can find strings in either fork of a file so there are two default editors. If the file selected in the Results Window is a data fork then the name of the default data fork editor is displayed on the leftmost button. If it is a resource fork then the name displayed will be that of the default resource fork editor (ResEdit in the example shown here). 
  329.  
  330. By default the two editors are "SimpleText" and ResEdit" but you can choose whatever application you like using the "Change" buttons shown above.  If ResEdit is not available on your Mac then the default resource fork editor is set to be SimpleText, as for the data fork.
  331.  
  332. For convenience you can choose what functions you wish Grapple to execute whenever you either double click on the block of text from a file or double click whilst pressing the Option key. In the example shown here Grapple will open the file at the first occurrence of the search string if you double click and will cause the file's folder to be opened and its icon selected if you press the option key then double click.
  333.  
  334. 6) Setting Start Folders for a Search.
  335.  
  336. You can easily build a list of your most useful starting folders and access it directly on the Grapple dialog. The popup menu beside the words "Start Folder" contains the list and you can add new items or delete old ones using the "Modify This Menu..." item at the end of the list.
  337.  
  338. You can also set the starting point for a search by dragging a folder over the Grapple application icon. The "Start Folder:" item on the main Grapple dialog will be updated to reflect the new starting point. You can search a whole disk in the same way - drag it over the Grapple icon, enter the search string and hit Return.
  339.  
  340. 7) Printing.
  341.  
  342. The contents of a Results Window can be printed on whatever printer you choose by choosing "Page Setup…" and "Print…" from the File menu. The text characteristics are set to be the same as in the Results Window.
  343.  
  344. 8) Search Statistics.
  345.  
  346. The details of all your searches to date can be viewed in the "About Grapple…" dialog.
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367. REGISTRATION
  368.  
  369. Grapple is Shareware. This means that you are honor bound to pay the registration fee if you continue to use it on a regular basis. The advantage to you in doing so is that you will increase the amount of quality software available at very low prices in the future by funding its development. We will continue to support our existing applications and develop new ones if you, the user, honor your side of the bargin.
  370.  
  371. If you register Grapple you can certainly experience that warm furry feeling of knowing you have done something right. But you also get the following benefits:
  372.  
  373.     •    personalised startup screen (or none at all) with no reminder to register.
  374.     •    free support by email or post.
  375.     •    access to any minor upgrades to another version 1.x free.
  376.     •    access to any major upgrade to 2.x at reduced price.
  377.  
  378. Fees.
  379. The registration fees for Grapple are:
  380. $20 per single user license,
  381. $300 for a site license. This covers installation of Grapple on up to 30 machines at one location in your organisation.
  382. $2000 for a world wide license. This covers installation of Grapple on any number of machines in your organisation.
  383.  
  384. How to Register.
  385. Our U.S. agent Kagi Shareware handles all the payment processing for Grapple. You can register on line, by phone, by email, by FAX or by regular mail!
  386.  
  387. To register on line point your browser at http://kagi.direct.net/cgi-bin/register1.cgi?HA
  388.  
  389. To register by phone call Kagi on +1 (510) 658-5244 (there is an additional charge for this service).
  390.  
  391. To register by email, FAX or regular mail open the Register program that accompanies Grapple. Enter your name, email address, and the number of single user licenses you desire for each program you wish to purchase (or Site or World-Wide licenses). Save, Copy or Print the data from the Register program and send the data and payment to Kagi Shareware. 
  392.  
  393. If paying by Credit Card or First Virtual, you can email the data to Kagi Shareware at sales@kagi.com. You 
  394. can FAX Kagi on 1 510 652-6589, or just Print the data to the Kagi FAX number if you have a FAX modem.
  395.  
  396. Payments sent via email are processed within 3 to 4 days while payments sent via FAX take up to 10 days.
  397.  
  398. If you are paying with Cash or USD Check you should print the data using the Register application and send it to the address shown on the form, which is: 
  399.  
  400.        Kagi Shareware
  401.        1442-A Walnut Street #392-HA
  402.        Berkeley, California 94709-1405
  403.        USA
  404.  
  405. You can pay with a wide variety of cash from different countries but at present if you pay via check, it must be a check drawn in US Dollars. Kagi Shareware cannot accept checks in other currencies due to the high cost. 
  406.  
  407. If you have a purchasing department, you can enter all the data into the Register program and then select Invoice as your payment method. Print three copies of the form and send it to your accounts payable people. You might want to highlight the line that mentions that they must include a copy of the form with their payment. Kagi Shareware can not invoice your company, you need to act on my behalf and generate the invoice and handle all the paperwork on your end. 
  408.  
  409. Payments send via regular mail take time to reach Kagi Shareware and then up to 10 days for processing. 
  410.  
  411. Whatever way you pay, if you include a correct email address, you will hear from Kagi Shareware when the payment is processed.
  412.  
  413. Registration Codes.
  414. When you register with Kagi Shareware you will receive an acknowledgement from Kagi if you have included your email address. You will then receive a registration code via email from PlaNet-3 software within a day or two of receiving the acknowledgement from Kagi.
  415.  
  416. If you have no email address then you will receive no acknowledgement from Kagi (unless you check paper receipt) but you will receive the registration code from PlaNet-3 by regular post. Depending on where you live this may take up to a week or more from the date Kagi receives the registration fees. Please give your complete postal address including the country where you live! 
  417.  
  418. Registration codes will be generated based on your name if you pay for a single user license, on your name and organisation name if you pay for a site license and on your organisation name only if you pay for a world-wide license.
  419.  
  420. Acknowledgements.
  421. The control definition function used to set the dates was written by James G. Stout and it's use is gratefully acknowledged.
  422.  
  423. DISTRIBUTION
  424.  
  425. This product must be distributed as SHAREWARE. This software may not be represented as anything other than shareware and the shareware concept must be explained in any advert or catalog that includes this software and on any packaging used to display the disk.
  426.  
  427. The unregistered version of the program may be distributed freely provided it is unaltered and distributed complete with any associated files. 
  428.  
  429. Disk Distributors and dealers must have written permission before selling copies of this disk. They must immediately stop selling/distributing copies of this software upon notice from the author.
  430.  
  431. You MAY NOT DISTRIBUTE this program on any disk costing more than $5 without the explicit permission of the author.  You MAY NOT DISTRIBUTE this program on any CD without the explicit permission of the author.
  432.  
  433. WARRANTY
  434.  
  435. This program is distributed in the hope that it will be useful, but without any warranty; without even the warranty of merchantability or fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you.
  436.     
  437. In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.
  438.